home *** CD-ROM | disk | FTP | other *** search
/ 17 Bit Software 5: The Fifth Dimension / 17 Bit - The Fifth Dimension (1995)(17 Bit Software)[!].iso / files / 3365.dms / 3365.adf / ARexxGuide2_0A.lha / ARexxGuide / ARexxGuide2_0A.readme < prev    next >
Text File  |  1994-04-10  |  12KB  |  313 lines
  1. Short: Complete ARexx reference. AmigaGuide.
  2. Type: util/rexx
  3. Uploader: robin@halcyon.com
  4. Author: Robin Evans
  5.  
  6. Keywords: ARexx,manual,reference,tutorial,AmigaGuide,script,TurboText,Edge,Ed
  7.  
  8.  DESCRIPTION
  9.  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10. ARexxGuide is a complete ARexx reference with tutorials and dozens
  11. of ready-to-use examples. Done in AmigaGuide format, it includes
  12. argument templates and descriptions of all instruction keywords, of
  13. built-in functions, and of the functions in rexxsupport.library.
  14. The basic elements of the language are fully explained. Example
  15. programs -- some of them interactive -- answer frequently-asked
  16. questions about the language. Sample clauses are included with each
  17. function and instruction explanation. Error codes and possible
  18. solutions are explained.
  19.  
  20. A help-system that will turn nearly any text editor into an online
  21. reference to ARexx is included. Working macros for three editors
  22. are provided as examples. A step-by-step tutorial explains the
  23. simple steps for making a new macro for a different editor.
  24.  
  25. ARexxGuide is a shareware offering. The suggested fee is $15.
  26.  
  27.  VERSION
  28.  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  29. 2.0a: Some embarrasing problems in the included scripts are fixed.
  30.       Those who previously downloaded the 2.0 version can get
  31.       copies of the fixed scripts in the archive ARexxG_20patch.lha.
  32.  
  33. The second edition includes extensive changes thoughout. Two new
  34. tutorials explain ARexx as a macro language. A new section on
  35. techniques answers frequently-asked questions about ARexx with
  36. example code that can often be plugged directly into a script. Each
  37. possible error code is explained.
  38.  
  39. Notes on compatability issues have been added throughout the guide.
  40. They show how ARexx differs from the standard definition of REXX
  41. and offer methods for handling the differences.
  42.  
  43. RQ version ======================
  44.  
  45. Two different versions of the second edition are distributed. Both
  46. include the same information, but present it in somewhat different
  47. ways. The RQ version uses requesters to show definitions and other
  48. information that is displayed in the standard version by moving to
  49. a new node. The RQ version uses `rexxreqtools.library' by Rafael
  50. D'Halleweyn. and `ReqTools' by Nico François to implement the
  51. requesters. Because the requesters must be able to communicate with
  52. AmigaGuide through ARexx, this version can be used only with
  53. pre-MultiView versions of AmigaGuide -- that is, with version 34 of
  54. the library.
  55.  
  56.  REQUIREMENTS
  57.  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  58. For the standard version: (ARexxGuide2_0A.lha)
  59.     Any AmigaGuide viewer.
  60.  
  61.     Multiview can be used with OS 3.x. Users of OS 1.3 or 2.x will
  62.     need the AmigaGuide utility and amigaguide.library which are
  63.     distributed by Commodore on most BBSes and networks that support
  64.     the Amiga.
  65.  
  66. For the RQ version: (ARexxGuide2_0rqA.lha)
  67.     AmigaGuide version 34 viewer and library.
  68.  
  69.     `reqtools.library' and `rexxreqtools.library'.
  70.  
  71.     These libraries are included in the distribution archives for
  72.     ReqTools by Nico François. Look for `ReqTools22a_User.lha' on
  73.     your favorite shareware source. A minimum version of 37.5 for
  74.     rexxreqtools.library is required.
  75.  
  76.  ARCHIVE CONTENTS
  77.  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  78. The ARexxGuide drawer of this archive contains 21 files that make
  79. up one AmigaGuide® application. The AmigaGuide files are:
  80.  
  81.   ArexxGuide.guide
  82.   ARx_Cmd.ag
  83.   ARx_Elements.ag
  84.   ARx_Elements2.ag
  85.   ARx_Elements3.ag
  86.   ARx_Func.ag
  87.   ARx_Func2.ag
  88.   ARx_Func3.ag
  89.   ARx_Func4.ag
  90.   ARx_Guide.xref
  91.   ARx_Index
  92.   ARx_Instr.ag
  93.   ARx_Instr2.ag
  94.   ARx_Instr3.ag
  95.   ARx_Intro.ag
  96.   ARx_Operator.ag
  97.   ARx_PrgUcr.ag
  98.   ARx_Tknq.ag
  99.   ARx_Tutor.ag
  100.   ARx_UcrTutor1.ag
  101.   ARx_UcrTutor2.ag
  102.  
  103. Only ARexxGuide.guide is intended as an AmigaGuide executable. The
  104. other files are called from within the main node of that guide.
  105.  
  106. The following ARexx script files, located in the same directory,
  107. are used to run interactive examples from ARexxGuide, or to provide
  108. utilities for the program:
  109.  
  110.   ARexxGuide.rexx
  111.   ARx_Cmpr.rexx
  112.   ARx_IactExamples.rexx
  113.   ARx_Reg.rexx
  114.   ARx_Setup.rexx
  115.   Arx_Trace.rexx
  116.  
  117. Two additional files are included with the RQ version of the guide.
  118.  
  119.   ARx_Glossary.rexx
  120.   ARx_GlossaryPort.rexx
  121.  
  122. The `Editors' drawer contains macros for the ARexxGuide help
  123. system. Example macros are included for Ed 2.0 (the editor that
  124. comes with the OS), TurboText, and Edge. A tutorial in ARexxGuide
  125. explains how to make a file for a different editor. Any editor that
  126. is capable of minimal communication with ARexx can be used.
  127.  
  128. The 'Extras' drawer contains some files that are not necessary, but
  129. may be helpful to some users. Read the opening comment for more
  130. information.
  131.  
  132. The file 'UnCrunch.rexx' is the the source document for the program
  133. included in the tutorial section.
  134.  
  135.  INSTALLATION
  136.  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  137. The ARexxGuide drawer can be moved to any location.
  138.  
  139. Once the drawer has been moved, click on the ARx_Setup.rexx icon to
  140. establish environmental variables that are used by the ARexxGuide
  141. utility programs. You will be asked if you want to store the
  142. variables permanently. If you answer Yes, they will be copied to
  143. your Envarc: directory.
  144.  
  145. You will also be asked if you want to copy the `.rexx' files from
  146. the ARexxGuide drawer to the REXX: directory. The files will be
  147. copied and deleted from the ARexxGuide drawer if you answer 'Yes'.
  148.  
  149. You could also move the .rexx files manually. The following command
  150. will do that:
  151.  
  152.    copy <path>/ARexxGuide/#?.rexx REXX:
  153.    delete <path>/ARexxGuide/#?.rexx
  154.  
  155. The icon labeled simply `ARexxGuide' runs a program called
  156. ARexxGuide.rexx when it is double clicked. If ARexxGuide.rexx is
  157. stored in the REXX: directory, the the icon can be kept anywhere
  158. you wish. It will launch ARexxGuide even if it's located in a
  159. different directory. You can move the icon anywhere on your system,
  160. but only with the shell copy command since it isn't actually
  161. attached to a file.
  162.  
  163.  
  164.  RUNNING ARexxGuide
  165.  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  166. System setup
  167.     The ARx_Setup.rexx script -- explained above in Installation --
  168.     will customize ARexxGuide for your system. If it is not run
  169.     before starting ARexxGuide, or if the environmental variables
  170.     set by the script are deleted, then the setup program will
  171.     sometimes be called by other ARexxGuide utility scripts.
  172.  
  173. From the ARexxGuide icon: (does not display '.guide' in the name)
  174.     This icon runs a script called ARexxGuide.rexx which should be
  175.     located either in the same directory as the icon or in the REXX:
  176.     directory. The default tool for this icon is `RX' without a path
  177.     specification. If the `RX' program is not in a command path that
  178.     is visible from Workbench, you will have to add a full path spec
  179.     to the icon's tool gadget. It would probably be something like
  180.     `sys:rexxc/rx'
  181.  
  182.     If you haven't run ARx_Setup.rexx before running this script,
  183.     then the setup script is called to set some of the environmental
  184.     variables needed to customize ARexxGuide for your system.
  185.  
  186.     If you have the function library rexxarplib.library, the script
  187.     lets you automatically display ARexxGuide on a public screen. If
  188.     you use the RQ version of the guide, the script will load the
  189.     requester data into memory before ARexxGuide is displayed and
  190.     will automatically close the requester port when the guide is
  191.     closed.
  192.  
  193. From the ARexxGuide.guide icon:
  194.    Double-click on the ARexxGuide.guide icon. ARexxGuide will open
  195.    its window.
  196.  
  197.    The default tool in the icon is 'AmigaGuide' without path
  198.    specification. If your AmigaGuide executable program is located
  199.    in a path that is searched by Workbench, then that will be
  200.    enough. If, however, AmigaGuide cannot be found by Workbench,
  201.    then you should single-click on the icon and press Amiga-I.  Add
  202.    the full path to the 'Default tool:' field in the Information
  203.    window.
  204.  
  205.       Example:
  206.             sys:utilities/Amigaguide
  207.  
  208.    If you use Multiview instead of AmigaGuide, then you will need to
  209.    change the default tool.
  210.  
  211.    When ARexxGuide is called from the icon, the .rexx interactive
  212.    examples will run, even if they are not moved to the rexx:
  213.    directory.
  214.  
  215. From a shell:
  216.    You have more options when you run ARexxGuide from a shell, but
  217.    may also run into a few more problems because this guide uses
  218.    multiple files. When pressing one of the link buttons in the
  219.    guide, AmigaGuide will often look for one of the subsidiary
  220.    files. It will find them if they are in the current directory or
  221.    if they are in a path included in the AmigaGuide/path
  222.    environmental variable.
  223.  
  224.  --- Run ARexxGuide from the current directory.
  225.  
  226.    Make the directory containing ARexxGuide.guide the current
  227.    directory before calling the guide:
  228.  
  229.       Example:
  230.          cd <path>/ARexxGuide
  231.          Amigaguide ARexxGuide.guide
  232.  
  233.    Interactive .rexx examples will run even if they are not moved
  234.    to REXX: when the guide is invoked this way.
  235.  
  236.  --- Add the ARexxGuide path the AmigaGuide search path.
  237.  
  238.    AmigaGuide will look for files in directories specified in the
  239.    environmental variable amigaguide/path. If you often run this
  240.    guide from a shell or directory utility, you should probably set
  241.    the variable.
  242.  
  243.    The enviromental variable is set automatically by the
  244.     ARx_Setup.rexx script, but it could also be set manually with
  245.     the following command, issued from a shell:
  246.  
  247.       makedir env:amigaguide
  248.       setenv amigaguide/path <path>/ARexxGuide
  249.  
  250.    where <path> is the full path leading to the directory.
  251.  
  252.    If you've already created an 'amigaguide' path in env:, then you
  253.    may omit the makedir command.
  254.  
  255.    Note that this command will replace any value that might
  256.    previously have been set for the path variable. (ARx_Setup will
  257.    not overwrite current settings, however.)
  258.  
  259.    You can,include multiple paths in that variable. Just separate
  260.    each path from others with a space and use the collection in the
  261.    'setenv' command.
  262.  
  263.    The env: directory is located by default in RAM:, so this
  264.    setting will not survive a reboot. If you'd like to have path
  265.    automatically set when you reboot, issue this command:
  266.  
  267.       copy env:amigaguide/#? envarc:
  268.  
  269.    If that command is issued after you have opened and closed
  270.    AmigaGuide, then the window size and position last used will
  271.    also be saved.
  272.  
  273.    Once the search path for AmigaGuide is set, ARexxGuide can be
  274.    run without setting the current directory. The interactive
  275.    examples, however, might not run. They should be moved to the
  276.    REXX: directory to so that ARexx will be able to find them.
  277.  
  278.  DISTRIBUTION
  279.  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  280. The files in this archive are copyright © 1993,1994 by Robin Evans
  281. and may be distributed only in the original form and only under the
  282. conditions outlined below.
  283.  
  284. Distribution of the material in this archive is prohibited if the
  285. contents of the original archive are altered in any way.
  286.  
  287. The archive may be distributed in its original form on local and
  288. national computer networks, on Aminet distribution channels
  289. (including the Walnut Creek CD-ROM), on Fish collections, or on
  290. disk collections distributed by non-profit entities. Distribution
  291. by other means (including distribution by profit-making entities
  292. other than those mentioned) is prohibited unless specific
  293. permission is granted.
  294.  
  295. Rights are reserved for other forms of distribution of this archive
  296. or of its contents individually, including but not limited to
  297. distribution of a printed version of any file contained in the
  298. archive, distribution with commercial products, or distribution on
  299. computer networks in hypertext form of any file in the archive.
  300. Contact the author for further information and permissions.
  301.  
  302.                Robin Evans                   24 Mar 1994
  303.  
  304.                   from Internet:
  305.                      robin@halcyon.com
  306.                      r.evans6@genie.geis.com
  307.  
  308.                   on GEnie:
  309.                      R.EVANS6
  310.  
  311.                   by phone:
  312.                      (206) 682-7077
  313.